---
title: Installation | gluestack-style
description: A Quick Installation guide for gluestack-style. To get started with gluestack-style, you'll need to install it using either npm or yarn.
---

import { Canvas, Meta, Story } from '@storybook/addon-docs';

<Meta title="styled/Getting Started/Install in Next.js" />

import {
  Hoverable,
  Button,
  AppProvider,
  HStack,
} from '@gluestack/design-system';

# Install in Next.js project

You can create a new Next.js project with [create-next-app](https://nextjs.org/docs).

## Installation

Install gluestack-style and it's peer dependencies using npm or yarn.

```bash
# using npm

npm i @gluestack-style/react react-native-web react-native-svg

# using yarn

yarn add @gluestack-style/react react-native-web react-native-svg
```

## Setup Config

To configure gluestack-style, you will need to create a `gluestack-style.config.ts` file (.js works too) in the root of your project. In this config file, you can define your theme tokens, breakpoints, and any other settings that you want to use throughout your application.

For example, in `gluestack-style.config.ts`:

```js
import { createConfig } from '@gluestack-style/react';

export const config = createConfig({
  aliases: {
    bg: 'backgroundColor',
    bgColor: 'backgroundColor',
    rounded: 'borderRadius',
    h: 'height',
    w: 'width',
  },
  tokens: {
    colors: {
      primary0: '#ffffff',
      primary400: '#c084fc',
      primary500: '#a855f7',
      primary600: '#9333ea',
    },
    space: {
      4: 16,
      5: 20,
      6: 24,
    },
    radii: {
      sm: 4,
      md: 6,
    },
    letterSpacings: {
      md: 0,
    },
    lineHeights: {
      sm: 20,
      md: 22,
    },
    fontWeights: {
      normal: '400',
      medium: '500',
    },
    fontSizes: {
      sm: 14,
      md: 16,
    },
    mediaQueries: {
      sm: '@media (min-width: 480px)',
      md: '@media (min-width: 768px)',
    },
  },
  globalStyle: {
    variants: {
      shadow: {
        softShadow: {
          shadowOffset: {
            width: 0,
            height: 0,
          },
          shadowRadius: 10,
          shadowOpacity: 0.1,
          _android: {
            shadowColor: '$primary500',
            elevation: 5,
            shadowOpacity: 0.05,
          },
        },
      },
    },
  },
} as const);

type ConfigType = typeof config;

declare module '@gluestack-style/react' {
  interface ICustomConfig extends ConfigType {}
}
```

## Setup StyledProvider

You need to setup `StyledProvider` with config at the root of your application. Once your config file is set up, you can import it and pass it as a prop to the `StyledProvider` component. This will make the configuration options available to all components using the styled function.

### Page router setup

If you are using page router, you can wrap your page component with `StyledProvider` in `pages/_app.tsx` or `pages/_app.jsx` file.

```jsx
import { config } from '@/gluestack-style.config';
import '@/styles/globals.css';
import { StyledProvider } from '@gluestack-style/react';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <StyledProvider config={config}>
      <Component {...pageProps} />
    </StyledProvider>
  );
}
```

### App directory setup

Next.js 13 introduces a new app/ directory / folder structure. By default it uses Server Components. However, gluestack-style only works in client-side components.

To use gluestack-style in server components, you need to convert them into client-side component by adding a `'use client';` at the top of your file.

To use gluestack-style in app directory, you can wrap `StyledProvider` in your own client Component. For example, in `app/provider.tsx`:

```jsx
'use client';

import { StyledProvider } from '@gluestack-style/react';
import React from 'react';
import { config } from '../../config';

const Provider = ({ children }: { children: React.ReactNode }) => {
  return <StyledProvider config={config}>{children}</StyledProvider>;
};

export default Provider;
```

You can wrap your root component with `StyledProvider` in `app/layout.tsx`.

```jsx
import './globals.css';
import Provider from './provider';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode,
}) {
  return (
    <html lang="en">
      <body>
        <Provider>{children}</Provider>
      </body>
    </html>
  );
}
```

> Note: You need to pass config to StyledProvider otherwise aliases and design tokens will not work.

## Setup next.config.js

To use gluestack-style with server-side rendering, you need to configure your project to transpile the modules correctly. The easiest way to do this is by using the `withGluestackUI` Next.js adapter. This adapter adds the necessary configuration to your project to ensure that your gluestack-style dependencies transpiled correctly for server-side rendering.

Install the adapter using npm or yarn:

```bash
# using npm

npm i @gluestack/ui-next-adapter

# using yarn

yarn add @gluestack/ui-next-adapter
```

Then, add the adapter to your `next.config.js` file:

```js
/** @type {import('next').NextConfig} */

const { withGluestackUI } = require('@gluestack/ui-next-adapter');
const nextConfig = {
  reactStrictMode: true,
};

module.exports = withGluestackUI(nextConfig);
```

## Server-side Rendering

It's also recommended to set up your server-side rendering (SSR) correctly. To do this, you will need to use the `flush()` function exported by the library and call it in your `_document.tsx` or `_document.jsx` file.

To prevent flickering, the `gs` class should be attached, which increases the specificity of any inline styles that are being used.

```jsx
import * as React from 'react';
import { Html, Head, Main, NextScript } from 'next/document';
import { AppRegistry } from 'react-native';
import { flush } from '@gluestack-style/react';

function Document() {
  return (
    <Html lang="en" className="gs">
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

export const style = `
html, body, #__next {
  width: 100%;
  /* To smooth any scrolling behavior */
  -webkit-overflow-scrolling: touch;
  margin: 0px;
  padding: 0px;
  /* Allows content to fill the viewport and go beyond the bottom */
  min-height: 100%;
}`;

Document.getInitialProps = async ({ renderPage }: any) => {
  AppRegistry.registerComponent('Main', () => Main);
  const { getStyleElement } = AppRegistry.getApplication('Main');
  const page = await renderPage();

  const styles = [
    // eslint-disable-next-line react/jsx-key
    <style dangerouslySetInnerHTML={{ __html: style }} />,
    getStyleElement(),
    ...flush(),
  ];
  return { ...page, styles: React.Children.toArray(styles) };
};

export default Document;
```

## Babel Plugin (Optional)

You can also add the babel plugin to your project if you want to perform all style calculations during build time. **The plugin can be installed via npm or yarn and should be added to your babel config**.

### Installation

Install it as development dependency.

```bash
# using npm

npm i --save-dev @gluestack-style/babel-plugin-styled-resolver

# using yarn

yarn add --dev @gluestack-style/babel-plugin-styled-resolver
```

### Usage

Add it to `babel.config.js` or `.babelrc`.

```jsx
// babel.config.js
module.exports = {
  plugins: ['@gluestack-style/babel-plugin-styled-resolver'],
};
```

or

```json
// .babelrc
{
  "plugins": ["@gluestack-style/babel-plugin-styled-resolver"]
}
```

## That's it 🎉

You are ready to use gluestack-style!

```jsx
import React from 'react';
import { styled } from '@gluestack-style/react';
import { View } from 'react-native';

const Box = styled(View, {
  bg: '$primary500',
  h: '$6',
  w: '$6',
});

const App = () => {
  return <Box />;
};

export default App;
```
